Qt5.4文档翻译：QXmlQuery类,QXmlQuery Class

QXmlQuery 类在XML 数据或者是已经弄得像XML 的非XML 数据上执行XQuer y 。 详细说明……

注意 ： 这个类中的所有函数都是 可重入的 。

详细说明

QXmlQuery 类在XML 数据或者是已经弄得像XML 的非XML 数据上执行XQuer y 。

QXmlQuery 类会对以 XQuery语言 编写的查询语句进行编译及执行。 QXmlQuery 一般用来查询XML 数据，但是， 它也可以对那种弄得看起来像XML 的非XML 数据进行查询。

如下面的代码片断所示，使用 QXmlQuery 来查询XML 数据是狠简单的，因为 ， 它可以使用内置的 XML数据模型 作为代理来 与底层的查询引擎进行交互，以遍历数据。内置 的数据模型是在 XQuery 1.0 和 XPath 2.0数据模型 中说明的。

QXmlQuery query;

query. setQuery ("doc('index.html')/html/body/p[1]");

QXmlSerializer serializer(query, myOutputDevice);

query. evaluateTo (&serializer);

这个示例代码，会使用 QXmlQuery 来匹配XML 文档 中的第一个段落 ，然后 将结果以XML的形式输出到一个设备 。

要想使用 QXmlQuery 来对 非 XML 数据进行查询的话，需要编写一个 QAbstractXmlNodeModel 子类，用来替代内置 的XML 数据模型。 自定义的数据模型应当能够按照 QAbstractXmlNodeModel 接口的要求来遍历该非XML 数据。然后 ， 该自定义数据模型的一个实例就会成为代理 ，被查询引擎用来遍历该非XML 数据。 欲观摩一下如何使用 QXmlQuery 来查询非XML 数据的话，则，参考 QAbstractXmlNodeModel 文档。

运行XQuery

要运行一个使用 QXmlQuery 建立的查询，则，调用其中 一个算值函数。

• •. evaluateTo ( QAbstractXmlReceiver  *) 这个函数的参数是一个XML  接收 器 指针， 该接收器会将查询结果当作一个回调序列来接收。 该接收器回调类与那些用来翻译某个SAX 解析 器的输出内容的回调类类似。例如， QXmlSerializer 就是一个接收器回调类， 会将回调序列翻译为未格式化的XML 文本。

• •. evaluateTo ( QXmlResultItems  *) 这个函数的参数是一个针对某个空白 的查询 结果条目 序列的迭代器指针。通过 这个 Java风格 的迭代器，可以串行 地访问那些查询结果。

• •. evaluateTo ( QStringList  *) 类似 于 evaluateTo ( QXmlResultItems  *) ，但是，对应 的查询必须能够被解释为一个字符串序列。

运行XPath表达式

XPath语言 是 XQuery 语言的一个子集，因此 ，运行XPath 表达 式与运行 XQuery 查询是相同的。使用 setQuery () 来将该XPath 表达式传递给 QXmlQuery 。

运行XSLT样式单

运行XSLT样式 单与运行 XQuery 类似，区别 就是， 当妳构造 QXmlQuery 的时候， 妳必须传入 QXmlQuery::XSLT20 ，以向 QXmlQuery 告知，应当 将它通过 setQuery ()接收到的东西解释为XSLT 样式 单，而不是解释成 XQuery 。 妳还必须通过调用 setFocus ()来设置输入文档。

QXmlQuery query( QXmlQuery ::XSLT20);

query.setFocus( QUrl ("myInput.xml"));

query.setQuery( QUrl ("myStylesheet.xsl"));

query.evaluateTo(out);

注意 ： 目前 ， 在使用XSLT 的时候，必须 在 setQuery () 之前 调用 setFocus ()。

另一种运行XSLT 样式单的方式就是，使用 xmlpatterns 这个命令行工具。

xmlpatterns myStylesheet.xsl myInput.xml

注意 ： 对于当前版本，XSLT 的支持应当被视作处于实验状态。参考 XSLT兼容 性 小节 以了解细节。

样式 单参数是使用 bindVariable ()来绑定的。

将一个查询绑定到某个起始节点

当妳在XML 数据上运行查询的时候，需要 指定查询 的起始点，例如上面的代码片断，使用 doc() 函数 来返回内置数据模型 中的一个节点 ，使得查询从该节点开始。但是，如果 妳是在一个包含着非XML 数据的 自定义节点模型 上运行查询的话，则，必须调用其中 的某个 bindVariable ()函数来将某个变量名字绑定到 该自定义模型中的某个起始节点。 在 XQuery 文本中会使用一个$变量引用 来访问 自定义模型中的起始节点。 不需要 在查询中将该变量名声明为外部的。参考 QAbstractXmlNodeModel 文档 中的示例。

可重入性及线程安全性

QXmlQuery 是可重入的，但不是线程安全的。 可以安全地使用Q X mlQuery （ ☯：原文是“ QxmlQuery ” ） 的复制构造函数来创建某个查询 的一个副本，并且多次运行同一个查询。 在台面下， QXmlQuery 会复用一些资源，例如已打开的文件和已编译的查询，将它们复用到极致程度。但是， 在多个线程中使用同一个 QXmlQuery 实例是不安全的。

错误处理

• •. 错误消息会被发送至 messageHandler ()。

• •. QXmlResultItems::hasError () 会返回真（ true ）， evaluateTo ()会返回假（ false ）；

• •.执行结果是未定义的。

资源管理

当 setQuery ()被调用时，查询文本 会被编译为一个内部的数据结构，并且会被优化。日后 ，优化后的形式可 在该查询的多次运行中被重用。由于 这个编译及优化过程可能会狠耗时 ，所以， 妳应当避免 在同一个查询对象上重复做这件事，而应当 针对每个查询文本使用一个单独的 QXmlQuery 实例。

一旦某个文档被解析完毕， 它的内部表示形式会被该 QXmlQuery 实例所维护，并且在多个 QXmlQuery 实例之间共享。

在使用 QXmlQuery 之前，必须有一个 QCoreApplication 实例存在。

事件处理

当 QXmlQuery 访问资源（例如，调用 fn:doc() 来载入一个文件，或者，通过绑定变量 来访问某个设备 ）的时候， 会使用到事件循环， 这就意味着，事件 会得到处理。 要想避免在 QXmlQuery 访问资源时处理事件，则，应当 在一个单独的线程中创建妳的 QXmlQuery 实例。

成员函数文档

void  QXmlQuery:: evaluateTo ( QXmlResultItems  *  result ) const

开始 算值过程，并且将其结果传递给 result 。如果 result 为空（null），那么，其行为是未定义的。 算值过程会随着调用 者使用 QXmlResultItems::next () 来获取下一个结果而渐进式（ 惰式算值 ）地进行。

参考 QXmlResultItems::next () 。

bool  QXmlQuery:: evaluateTo ( QAbstractXmlReceiver  *  callback ) const

对这个查询进行算值，并且，将结果 以一个回调序列的形式发送给 接收 者 callback 。 QXmlQuery 不会获取 callback 的所有权。

如果 在算值过程中发生错误，则，错误消息 会被发送至 messageHandler ()，并且会返回假（ false ）。

如果 该查询是 无效 的 ，则，会返回假（ false ），并且其行为是未定义的。如果 callback 为空（null），则，其行为是未定义的。

参考 QAbstractXmlReceiver 和 isValid () 。

bool  QXmlQuery:: evaluateTo ( QStringList  *  target ) const

尝试 对该查询进行算值，并且， 将结果返回至 target 这个 字符串列表 。

如果 该查询 是有效的 并且算值成功，则，会返回真（true）。否则， 会返回假（false），并且 target 的内容会是未定义的。

该查询必须能够被算值为一系列的 xs:string 值 组成的序列。如果 该查询的算值结果不是 一个字符串序列的话，则，通常 会在 XQuery 结束的时候调用 string() 来将那些值转换成字符串。

如果 callback 为空（null），则，其行为是未定义的。

bool  QXmlQuery:: evaluateTo ( QString  *  output ) const

对该查询进行算值，并且，将输出内容序列化成XML，传递给 output 。

如果 在算值过程中发生错误，则，错误消息会被发送至 messageHandler ()，并且， output 的内容会是未定义的，并且，会返回假（ false ），否则，会返回真（ true ）。

如果 output 为空（ null ），则，其行为是未定义的。 QXmlQuery 不会获取 output 的所有权。

在内部，会使用 QXmlFormatter 类。

这个函数是从Qt 4.5 开始引入的。

bool  QXmlQuery:: evaluateTo ( QIODevice  *  target ) const

对该查询或样式单进行算值，并且将输出内容写入到 target 。

QXmlSerializer 被用来向 target 中写入输出内容。 在日后的某个版本中，可能会做出改动，使得 这个函数遵守样式单中设置的序列化选项。

如果 在算值过程中出现错误，那么，错误消息会 被发送至 messageHandler ()，并且会返回假（ false ）。

如果 target 为空（ null ），或者 不是以 QIODevice::WriteOnly 及更高级别打开的，则，其行为是未定义的。 QXmlQuery 不会获取 target 的所有权。

这是一个重载函数。

这个函数是从Qt 4.5 开始引入的。

void  QXmlQuery:: setQuery ( QIODevice  *  sourceCode , const  QUrl  &  documentURI  = QUrl())

将这个 QXmlQuery 设置为从 sourceCode 设备中读取的 XQuery 。设备必须已经按照 QIODevice::ReadOnly 及更高的级别打开。

documentURI  表示 从 sourceCode 设备中获取到的查询。按照 XQuery语言 的定义，它是静态上下文的基准URI。 在内部，它被用于解析那些 在查询中出现的相对URI，并且用来进行消息的报告。 documentURI 可以为空。如果 它为空，则，会使用 应用程序本身文件 的路径 。如果 它不为空，则， 它可能是相对的或绝对的。如果 它是相对的，则， 会首先按照 应用程序本身文件 的路径 来解析自身。如果 documentURI 既不是一个有效的URI，也不是空白的，则，其结果是未定义的。

如果 该查询中包含着一个静态错误（例如，语法错误），则， 会向 messageHandler ()发送一个错误消息，并且， isValid ()会返回假（ false ）。

在调用setQuery()之前，必须先做好变量的绑定。

在内部，会按照 XQuery 文件 的设置选项和编码检测规则来检测 sourceCode 中 XQuery 的编码，这些规则在 XQuery语言 中有说明。

如果 sourceCode 为空（ null ）或者不可读取，或者 documentURI 不是一个有效的URI，则，其行为是未定义的。

参考 isValid () 。

void  QXmlQuery:: setQuery (const  QUrl  &  queryURI , const  QUrl  &  baseURI  = QUrl())

将这个 QXmlQuery 设置为从 queryURI 中读取到的 XQuery 。 在调用了这个函数之后请调用 isValid ()。如果 在读取 queryURI 的过程中出错了，比如说查询 不存在、无法被读取或者是无效的 ，则， isValid ()会返回假（ false ）。

所支持的URI 模式，与 XQuery 的 fn:doc 函数中的那些模式是相同的，只有一个例外，queryURI 可以是 与某个变量绑定的对象。

 is根据 XQuery语言 的定义， baseURI 是静态上下文的基准URI。 在内部，它被用于 对查询中出现的相对URI进行解析，以及用于消息的报告。如果 baseURI 为空，则会使用 queryURI 。否则， 会使用 baseURI ，并且，如果它是相对的，则会根据 应用程序自身文件 的路径 来解析它。

如果queryURI 为空或者无效，或者 baseURI 无效，则，其行为是未定义的。

void  QXmlQuery:: setQuery (const  QString  &  sourceCode , const  QUrl  &  documentURI  = QUrl())

这是一个重载函数。

其行为和要求，就跟 setQuery ( QIODevice *, const  QUrl &)那个函数中 在从输入/输出设备读取到 XQuery 之后一样。因为 sourceCode 已经 是一个Unicode 字符串了，所以，不需要进行编码检测。

巧慧

着火 的瀑布